<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 

<TITLE>Extensible 3D (X3D), ISO/IEC FCD 19775-1r1:200x, 38 Picking sensor component</TITLE>
<link rel="stylesheet" href="../X3D.css" type="text/css">

</HEAD>
<BODY>

<div class="CenterDiv">
<IMG class="x3dlogo" SRC="../../Images/x3d.png" ALT="X3D logo" style="width: 176px; height: 88px"> 
</div>

<div class="CenterDiv">
<p class="HeadingPart">
    Extensible 3D (X3D)<br />
    Part 1: Architecture and base components</p>
<p class="HeadingClause">38 Picking sensor component</p>
</div>

<IMG class="x3dbar" SRC="../../Images/x3dbar.png" ALT="--- X3D separator bar ---" width="430" height="23">

<h1><a name="Introduction"></a>
<img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19"> 
38.1 Introduction</h1>
<h2><a name="Name"></a>38.1.1 Name</h2>
<p>The name of this component is &quot;PickingSensor&quot;. This name shall be used when referring 
to this component in the COMPONENT statement (see
<a href="core.html#COMPONENTStatement">7.2.5.4 Component statement</a>).</p>
<h2><a name="Overview"></a>38.1.2 Overview</h2>

<p>This component provides the ability to test for arbitrary object collision in 
a somewhat limited form. In traditional 3D graphics terminology, this is termed 
picking. The intention is to not support full n-body object collision, but to 
provide an extended set of basic capabilities to provide some limited custom 
interactions, such as terrain following.
<a href="#t-Topics">Table 
  38.1</a> provides links to the major topics in this clause.</p>

<div class="CenterDiv">

<p class="TableCaption">
<a name="t-Topics"></a><b>
Table 38.1 &#8212; Topics</b></p>

  <table>
    <tr> 
      <td> 
        <ul>
          <li><a href="#Introduction">38.1 Introduction</a>
            <ul>
              <li><a href="#Name">38.1.1 Name</a></li>
              <li><a href="#Overview">38.1.2 Overview</a></li>
            </ul></li>
		  <li><a href="#Concepts">38.2 Concepts</a> 
            <ul>
              <li><a href="#OverviewOfPointingDeviceSensors">38.2.1 Event model interaction</a></li>
            </ul></li>
          <li><a href="#Abstracttypes">38.3 Abstract types</a>  
            <ul>
              <li><a href="#X3DPickableObject">38.3.1 <i>X3DPickableObject</i></a></li>
              <li><a href="#X3DPickingNode">38.3.2 <i>X3DPickingNode</i></a></li>
            </ul></li>
          <li><a href="#Nodereference">38.4 Node reference</a>  
            <ul>
              <li><a href="#LinePicker">38.4.1 LinePicker</a><li>
			  <li><a href="#PickableGroup">38.4.2 PickableGroup</a></li>
			  <li><a href="#PointPicker">38.4.3 PointPicker</a></li>
              <li><a href="#PrimitivePicker">38.4.4 PrimitivePicker</a></li>
              <li><a href="#VolumePicker">38.4.5 VolumePicker</a></li>
            </ul></li>
          <li><a href="#SupportLevels">38.5 Support levels</a></li> 
        </ul>
        <ul>
          <li><a href="#t-Topics">Table 38.1 &#8212; Topics</a></li>
          <li><a href="#t-supportlevels">Table 38.2 &#8212; Pointing device sensor component support levels</a></li>
        </ul>
      </td>
    </tr>
  </table>
</div>

<h1><img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19">
<a name="Concepts"></a>38.2 Concepts</h1>

<h2><a name="OverviewOfPointingDeviceSensors"></a>38.2.1 Event model interaction</h2>

<p>Picking notification is performed at the start of the frame when all other 
sensors are processed. This allows the user to manipulate geometry and have the 
pick results returned at the start of the frame, thus guaranteeing a fixed, 
known state at all times.</p>

<h1><img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19">
<a name="Abstracttypes"></a>
38.3 Abstract types</h1>

<h2><a name="X3DPickableObject"></a>38.3.1 <i>X3DPickableObject</i></h2>

<pre class="node">X3DPickableObject {
  MFString [in,out] objectType &quot;ALL&quot; [&quot;ALL&quot;|&quot;NONE&quot;|&quot;TERRAIN&quot;|...]
  SFBool   [in,out] pickable
}
</pre>

<p>The <i>X3DPickableObject</i> abstract object type marks a node as being capable of having customized 
picking performed on the its contents or children.</p>
<p>The <i>pickable</i> field is used to independently control whether picking 
may be performed on this node or its children. Setting the value to <code>FALSE</code> 
will remove the children from the list of potential matches for picking. This 
only effects children that are accessed through the transformation hierarchy of 
the parent. If one or more of the children of this instance is accessible 
through another transformation hierarchy through DEF/USE that still has picking 
enabled, they shall still be pickable through that path only. </p>
<p>The <i>objectType</i> field specifies a label that is used in the picking 
process. Each string specified is treated as an independent label that needs to 
be matched against the same type in one of the picking node instances. For 
example, labeling a group with the value <span class="code">&quot;WATER&quot;</span> and 
then attempting to intersect a picker with the <i>objectType</i>
<span class="code">&quot;GROUND&quot;</span> would fail as the types are not matching. The 
special type <span class="code">&quot;ALL&quot;</span> means that it is available for 
picking regardless of the type specified by the picking node. The
<span class="code">&quot;NONE&quot;</span> field value or empty field declaration 
effectively disables all picking for this node and is the equivalent of setting 
the <i>pickable</i> field to <span class="code">FALSE</span>. The user may 
define any value for flags.</p>

<h2><a name="X3DPickingNode"></a>38.3.2 <i>X3DPickingNode</i></h2>

<pre class="node">X3DPickingNode : X3DSensorNode { 
  SFBool   [in,out] enabled
  SFNode   [in,out] metadata         NULL      [X3DMetadataObject]
  MFString [in,out] objectType       &quot;ALL&quot;     [&quot;ALL&quot;,&quot;NONE&quot;,&quot;TERRAIN&quot;,...]
  SFNode   [in,out] pickingGeometry  NULL      [X3DGeometryNode]
  MFNode   [in,out] pickTarget       []        [X3DGroupingNode|X3DShapeNode]
  MFNode   [out]    pickedGeometry
  SFBool   [out]    isActive
  SFString []       intersectionType &quot;BOUNDS&quot;  [&quot;GEOMETRY&quot;|&quot;BOUNDS&quot;]
  SFString []       sortOrder        &quot;CLOSEST&quot; [&quot;CLOSEST&quot;|&quot;ALL&quot;|&quot;ALL_SORTED&quot;]
}
</pre>

<p>The <i>X3DPickingNode</i> abstract node type is the base node type that represents the lowest common 
denominator of picking capabilities. An <i>X3DPickingNode</i> is a type of <i>
X3DSensorNode</i>. <i>isActive</i> is <span class="code">TRUE</span> whenever 
there is a picked item available. If the intersecting object is not picked by 
the picking geometry, the sensor is not active.</p>
<p>The <i>intersectionType</i> field specifies the precision of the collision 
computation. The <i>intersectionType</i> constants may be extended by the 
individual concrete node to provide addtional options.</p>
<p class="Example">EXAMPLE 1&nbsp; An <i>intersectionType</i> may be used to 
specify the specific algorithm used for the detection.</p>
<p>The <i>objectType</i> field lists the types of object that are to be tested 
for intersections. An arbitrary label may be specified here in addition to the 
predefined types. </p>
<p>The <i>pickingGeometry</i> field specifies the exact coordinates of the 
geometry that will be performing the intersection testing. The acceptable range 
of node types and how they are to be interpreted shall be defined by the 
individual concrete nodes.</p>
<p>The <i>pickTarget</i> field specifies the list of nodes against which the 
picking operation should be performed. If a the descendent of the nodes declared 
in this field include another <i>X3DPickingNode</i> instance, the children of 
the descendent <i>X3DPickingNode</i> are not considered for picking.</p>
<p>The <i>pickedGeometry</i> field communicates the node or nodes that have been 
found to intersect with the picking geometry from the last time this node 
performed a picking operation. The values provided shall be dependent on the 
setting of the <i>sortOrder</i> field.</p>
<p class="Example">EXAMPLE 2&nbsp; If the sortOrder is <span class="code">&quot;CLOSEST&quot;,</span> 
the values in the <i>pickedGeometry</i> field will be ordered in the array 
starting with the closest intersecting object first proceeding to the farthest 
last.</p>
<p>This node is not considered to be part of the transformation hierarchy. 
Children nodes of this node shall not be visible on screen. Children of this 
node are not eligible for picking from any other node.</p>

<h1><img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19">
<a name="Nodereference"></a>
38.4 Node reference</h1>
 
<h2><a name="LinePicker"></a>38.4.1 LinePicker</h2>

<pre class="node">LinePicker : X3DPickingNode { 
  SFBool   [in,out] enabled                 TRUE
  SFNode   [in,out] metadata                NULL      [X3DMetadataObject]
  MFString [in,out] objectType              &quot;ALL&quot;     [&quot;ALL&quot;,&quot;NONE&quot;,&quot;TERRAIN&quot;,...]
  SFNode   [in,out] pickingGeometry         NULL      [IndexedLineSet|LineSet]
  MFNode   [in,out] pickTarget              []        [X3DGroupingNode|X3DShapeNode]
  SFBool   [out]    isActive
  MFNode   [out]    pickedGeometry
  MFVec3f  [out]    pickedNormal
  MFVec3f  [out]    pickedPoint
  MFVec2f  [out]    pickedTextureCoordinate
  SFString []       intersectionType        &quot;BOUNDS&quot;  [&quot;GEOMETRY&quot;|&quot;BOUNDS&quot;]
  SFString []       sortOrder               &quot;CLOSEST&quot; [&quot;CLOSEST&quot;|&quot;ALL&quot;|&quot;ALL_SORTED&quot;]
}</pre>
<p>The LinePicker node picks one or more line segments as the test object with 
which to pick. As a line is a known point in space, normal, geometry and 
texCoord information can be returned that is useful.<br>
</p>

<h2><a name="PickableGroup"></a>38.4.2 PickableGroup</h2>

<pre class="node">PickableGroup : X3DGroupingNode, X3DPickableObject { 
  MFNode   [in]     addChildren
  MFNode   [in]     removeChildren
  MFNode   [in,out] children       []       [X3DChildNode]
  SFNode   [in,out] metadata       NULL     [X3DMetadataObject]
  MFString [in,out] objectType     &quot;ALL&quot;    [&quot;ALL&quot;,&quot;NONE&quot;,&quot;TERRAIN&quot;,...]
  SFBool   [in,out] pickable       TRUE
  SFVec3f  []       bboxCenter     0 0 0    (-inf,inf)
  SFVec3f  []       bboxSize       -1 -1 -1 [0,inf) or -1 -1 -1
}</pre>
<p>A PickableGroup node contains <i>children</i> that can be marked as being of 
a given classification of picking types, as well as the ability to enable or 
disable picking of the <i>children</i>.</p>
<p>For field definitions, see <a href="#X3DPickableObject">38.3.1 <i>X3DPickableObject</i></a><i>.</i><br>
</p>

<h2><a name="PointPicker"></a>38.4.3 PointPicker</h2>

<pre class="node">PointPicker : X3DPickingNode { 
  SFBool   [in,out] enabled          TRUE
  SFNode   [in,out] metadata         NULL      [X3DMetadataObject]
  MFString [in,out] objectType       &quot;ALL&quot;     [&quot;ALL&quot;,&quot;NONE&quot;,&quot;TERRAIN&quot;,...]
  SFNode   [in,out] pickingGeometry  NULL      [PointSet]
  MFNode   [in,out] pickTarget       []        [X3DGroupingNode|X3DShapeNode]
  SFBool   [out]    isActive
  MFNode   [out]    pickedGeometry
  MFVec3f  [out]    pickedPoint
  SFString []       intersectionType &quot;BOUNDS&quot;  [&quot;GEOMETRY&quot;|&quot;BOUNDS&quot;]
  SFString []       sortOrder        &quot;CLOSEST&quot; [&quot;CLOSEST&quot;|&quot;ALL&quot;|&quot;ALL_SORTED&quot;]
}</pre>The PointPicker node tests one or more points in space as lying inside 
the provided target geometry. For each point that lies inside the geometry, the 
point coordinate is returned in the output array with the corresponding geometry 
inside which the point lies.
<p>Because points are just a location in space, the <span class="code">&quot;CLOSEST&quot;</span> 
and <span class="code">&quot;ALL_SORTED&quot;</span> sort orders are defined to mean
<span class="code">&quot;ANY&quot;</span> and <span class="code">&quot;ALL&quot;</span> 
respectively.</p>

<h2><a name="PrimitivePicker"></a>38.4.4 PrimitivePicker</h2>

<pre class="node">PrimitivePicker : X3DPickingNode { 
  SFBool   [in,out] enabled          TRUE
  SFNode   [in,out] metadata         NULL      [X3DMetadataObject]
  MFString [in,out] objectType       &quot;ALL&quot;     [&quot;ALL&quot;,&quot;NONE&quot;,&quot;TERRAIN&quot;,...]
  SFNode   [in,out] pickingGeometry  NULL      [Cone|Cylinder|Sphere|Box]
  MFNode   [in,out] pickTarget       []        [X3DGroupingNode | X3DShapeNode]
  SFBool   [out]    isActive
  MFNode   [out]    pickedGeometry
  SFString []       intersectionType &quot;BOUNDS&quot;  [&quot;GEOMETRY&quot;|&quot;BOUNDS&quot;]
  SFString []       sortOrder        &quot;CLOSEST&quot; [&quot;CLOSEST&quot;|&quot;ALL&quot;|&quot;ALL_SORTED&quot;]
}
</pre>

The PrimitivePicker node picks one of the basic primitive object types against 
the target geometry.<p>Boolean fields used to control visibility of subsections 
of a primitive are ignored when evaluating the picking routines.</p>
<p class="Example">EXAMPLE&nbsp; A cylinder missing the end caps is still 
treated as an enclosed cylinder. </p>
<p>Sorting is defined based on the primitive type, as follows:</p>
<ol type="a">
	<li>For cone, the picked primitive is closest to the vertex point.</li>
	<li>For cylinder, box, and sphere, the picked primitive is closest to the 
	center.</li>
</ol>

<h2><a name="VolumePicker"></a>38.4.5 VolumePicker</h2>

<pre class="node">VolumePicker : X3DPickingNode { 
  SFBool   [in,out] enabled          TRUE
  SFNode   [in,out] metadata         NULL      [X3DMetadataObject]
  MFString [in,out] objectType       &quot;ALL&quot;     [&quot;ALL&quot;,&quot;NONE&quot;,&quot;TERRAIN&quot;,...]
  SFNode   [in,out] pickingGeometry  NULL      [X3DGeometryNode]
  MFNode   [in,out] pickTarget       []        [X3DGroupingNode | X3DShapeNode]
  SFBool   [out]    isActive
  MFNode   [out]    pickedGeometry
  SFString []       intersectionType &quot;BOUNDS&quot;  [&quot;GEOMETRY&quot;|&quot;BOUNDS&quot;]
  SFString []       sortOrder        &quot;CLOSEST&quot; [&quot;CLOSEST&quot;|&quot;ALL&quot;|&quot;ALL_SORTED&quot;]
}
</pre>

<p>The VolumePicker picks against an arbitrary volume defined by the geometry. 
The volume is defined by the convex hull of the enclosing planes of the provided 
geometry.</p>

<h1><img class="cube" src="../../Images/cube.gif" alt="cube" width="20" height="19">
<a name="SupportLevels"></a>38.5 Support levels</h1>

<p>The Pointing Device Sensor component provides one level of support as specified 
  in <a href="#t-supportlevels">Table 38.2</a>. </p>

<div class="CenterDiv">

<p class="TableCaption">
<a name="t-supportlevels"></a>
Table 38.2<b>
&#8212; Pointing device sensor</b> component support levels</p>
  
<table>
      <tr> 
        <th>Level</th>
        <th>Prerequisites</th>
        <th>Nodes/Features</th>
        <th>Support</th>
      </tr>
      <tr> 
        <td align="center"><b>1</b></td>
        <td>Core 1<br>
		Grouping 1<br>
		Shape 1<br>
		Rendering 1</td>
        <td></td>
        <td></td>
      </tr>
      <tr>
        <td align="center"></td>
        <td></td>
        <td><i>X3DPickingNode</i></td>
        <td>n/a</td>
      </tr>
      <tr> 
        <td align="center"></td>
        <td></td>
        <td><i>X3DPickableObject</i></td>
        <td>n/a</td>
      </tr>
      <tr> 
        <td align="center"></td>
        <td></td>
        <td>LinePicker</td>
        <td>All fields fully supported.</td>
      </tr>
      <tr> 
        <td align="center"></td>
        <td></td>
        <td>PickableGroup</td>
        <td>All fields fully supported.</td>
      </tr>
      <tr> 
        <td align="center"></td>
        <td></td>
        <td>PointPicker</td>
        <td>All fields fully supported.</td>
      </tr>
      <tr>
        <td align="center"><b>2</b></td>
        <td>Core 1<br>
		Grouping 1<br>
		Shape 1<br>
		Rendering 1</td>
        <td>&nbsp;</td>
        <td>&nbsp;</td>
      </tr>
      <tr>
        <td align="center">&nbsp;</td>
        <td>&nbsp;</td>
        <td>All Level 1 nodes</td>
        <td>All fields fully supported.</td>
      </tr>
      <tr>
        <td align="center">&nbsp;</td>
        <td>&nbsp;</td>
        <td>PrimitivePicker</td>
        <td>All fields fully supported.</td>
      </tr>
      <tr>
        <td align="center"><b>3</b></td>
        <td>Core 1<br>
		Grouping 1<br>
		Shape 1<br>
		Rendering 1</td>
        <td>&nbsp;</td>
        <td>&nbsp;</td>
      </tr>
      <tr>
        <td align="center">&nbsp;</td>
        <td>&nbsp;</td>
        <td>All Level 2 nodes</td>
        <td>All fields fully supported.</td>
      </tr>
      <tr>
        <td align="center">&nbsp;</td>
        <td>&nbsp;</td>
        <td>VolumePicker</td>
        <td>All fields fully supported.</td>
      </tr>
    </table>
</div>

<img class="x3dbar" src="../../Images/x3dbar.png" alt="--- X3D separator bar ---" width="430" height="23" />

</body>
</html>